﻿<article>
  <section class="markdown"><h1>Modal 对话框</h1>
    <section class="markdown"><p>模态对话框。</p>
      <h2 id="何时使用"><span>何时使用</span>
        <!-- <a class="anchor">#</a> -->
      </h2>
      <p>需要用户处理事务，又不希望跳转页面以致打断工作流程时，可以使用 <code>Modal</code> 在当前页面正中打开一个浮层，承载相应的操作。</p>
      <p>推荐使用加载Component的方式弹出Modal，这样可以弹出层的Component逻辑可以与上层Component完全隔离，并且做到可以随时复用</p>
      <p>在弹出层Component中可以通过`NzModalSubject`向外层Component传出数据</p>
      <p>另外当需要一个简洁的确认框询问用户时，可以使用精心封装好的 <code>NzModalService.confirm()</code> 等方法。</p>
    </section>
    <h2>代码演示<i class="code-box-expand-trigger anticon anticon-appstore" title="展开全部代码"></i></h2>
  </section>
  <nz-row [nzGutter]="8">
    <div nz-col [nzSpan]="12">
      <nz-code-box [nzTitle]="'基本'" id="components-modal-demo-basic" [nzCode]="NzDemoModalBasicCode">
        <nz-demo-modal-basic demo></nz-demo-modal-basic>
        <div intro>
          <p>最简单的用法。</p>
        </div>
      </nz-code-box>
      <nz-code-box [nzTitle]="'Modal\'s service'" id="components-modal-demo-service" [nzCode]="NzDemoModalServiceCode">
        <nz-demo-modal-service demo></nz-demo-modal-service>
        <div intro>
          <p>Modal的service用法，示例中演示了用户自定义模板、自定义component、以及获取传出数据的方法。<br/></p>
          <div class="markdown">
            <blockquote><b>注意：</b>如果使用component模式，则需要在NgModule中的 <code>declarations</code> 和
              <code>entryComponents</code> 加入自定义的component
            </blockquote>
          </div>
          <br>

        </div>
      </nz-code-box>
      <nz-code-box [nzTitle]="'异步确认对话框'" id="components-confirm-demo-async" [nzCode]="NzDemoConfirmAsyncCode">
        <nz-demo-confirm-async demo></nz-demo-confirm-async>
        <div intro>
          <p>使用 <code>confirm()</code> 可以快捷地弹出确认框。onCancel/onOk 返回 promise 可以延迟关闭</p>
        </div>
      </nz-code-box>
      <nz-code-box [nzTitle]="'国际化'" id="components-modal-demo-locale" [nzCode]="NzDemoModalLocaleCode">
        <nz-demo-modal-locale demo></nz-demo-modal-locale>
        <div intro>
          <p>设置 <code>okText</code> 与 <code>cancelText</code> 以自定义按钮文字。</p>
        </div>
      </nz-code-box>
      <nz-code-box [nzTitle]="'自定义位置'" id="components-modal-demo-style" [nzCode]="NzDemoModalStyleCode">
        <nz-demo-modal-style demo></nz-demo-modal-style>
        <div intro>
          <p>您可以直接使用 <code>style.top</code> 或配合其他样式来设置对话框位置。<br/></p>
          <div class="markdown">
            <blockquote><b>注意：</b>如果在component中没有加入
              <code>encapsulation: ViewEncapsulation.None</code> 则因为样式隔离，必须在自定义样式时加上
              <code> :host ::ng-deep </code> ，否则样式不生效。</blockquote>
          </div>
          <br>
        </div>
      </nz-code-box>
    </div>
    <div nz-col [nzSpan]="12">
      <nz-code-box [nzTitle]="'异步关闭'" id="components-modal-demo-async" [nzCode]="NzDemoModalAsyncCode">
        <nz-demo-modal-async demo></nz-demo-modal-async>
        <div intro>
          <p>点击确定后异步关闭对话框，例如提交表单。</p>
        </div>
      </nz-code-box>
      <nz-code-box [nzTitle]="'自定义'" id="components-modal-demo-customize" [nzCode]="NzDemoModalCustomizeCode">
        <nz-demo-modal-customize demo></nz-demo-modal-customize>
        <div intro>
          <p>更复杂的例子，自定义了页头的内容及页脚的按钮，点击提交后进入 loading 状态，完成后关闭。</p>
        </div>
      </nz-code-box>
      <nz-code-box [nzTitle]="'确认对话框'" id="components-confirm-demo-basic" [nzCode]="NzDemoConfirmBasicCode">
        <nz-demo-confirm-basic demo></nz-demo-confirm-basic>
        <div intro>
          <p>使用 <code>confirm()</code> 可以快捷地弹出确认框。</p>
        </div>
      </nz-code-box>
      <nz-code-box [nzTitle]="'信息提示'" id="components-confirm-demo-info" [nzCode]="NzDemoConfirmInfoCode">
        <nz-demo-confirm-info demo></nz-demo-confirm-info>
        <div intro>
          <p>各种类型的信息提示，只提供一个按钮用于关闭。</p>
        </div>
      </nz-code-box>
      <nz-code-box [nzTitle]="'手动移除'" id="components-confirm-demo-destroy" [nzCode]="NzDemoConfirmDestroyCode">
        <nz-demo-confirm-destroy demo></nz-demo-confirm-destroy>
        <div intro>
          <p>手动关闭modal。</p>
        </div>
      </nz-code-box>
    </div>
  </nz-row>
  <section class="markdown api-container">
    <h2 id="API"><span>API</span>
      <!-- <a class="anchor">#</a> -->
    </h2>
    <table>
      <thead>
        <tr>
          <th>参数</th>
          <th>说明</th>
          <th>类型</th>
          <th>介绍</th>
          <th>默认值</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>nzVisible</td>
          <td>对话框是否可见</td>
          <td>Boolean</td>
          <td>双向绑定</td>
          <td>-</td>
        </tr>
        <tr>
          <td>nzConfirmLoading</td>
          <td>确定按钮 loading</td>
          <td>Boolean</td>
          <td></td>
          <td>-</td>
        </tr>
        <tr>
          <td>nzTitle</td>
          <td>标题</td>
          <td>String or TemplateRef</td>
          <td>如果不传，则不展示标题。如果需传入TemplateRef，可使用<code>template</code>，具体见实例</td>
          <td>-</td>
        </tr>
        <tr>
          <td>nzClosable</td>
          <td>是否显示右上角的关闭按钮</td>
          <td>Boolean</td>
          <td></td>
          <td>true</td>
        </tr>
        <tr>
          <td>nzBody</td>
          <td>内容</td>
          <td>String or TemplateRef</td>
          <td>如果需传入TemplateRef，可使用<code>template</code>，具体见实例</td>
          <td>-</td>
        </tr>
        <tr>
          <td>nzOnOk</td>
          <td>点击确定回调</td>
          <td>function</td>
          <td></td>
          <td>无</td>
        </tr>
        <tr>
          <td>nzOnCancel</td>
          <td>点击遮罩层或右上角叉或取消按钮的回调</td>
          <td>function</td>
          <td></td>
          <td>无</td>
        </tr>
        <tr>
          <td>nzWidth</td>
          <td>宽度</td>
          <td>String or Number</td>
          <td></td>
          <td>520</td>
        </tr>
        <tr>
          <td>nzFooter</td>
          <td>底部内容</td>
          <td>TemplateRef</td>
          <td>只支持TemplateRef，具体见实例</td>
          <td>确定取消按钮</td>
        </tr>
        <tr>
          <td>nzOkText</td>
          <td>确认按钮文字</td>
          <td>String</td>
          <td>如果使用了<code>template</code>来定义nzFooter，<br/>则配置无效</td>
          <td>确定</td>
        </tr>
        <tr>
          <td>nzCancelText</td>
          <td>取消按钮文字</td>
          <td>String</td>
          <td>如果使用了<code>template</code>来定义nzFooter，<br/>则配置无效</td>
          <td>取消</td>
        </tr>
        <tr>
          <td>nzMaskClosable</td>
          <td>点击蒙层是否允许关闭</td>
          <td>Boolean</td>
          <td></td>
          <td>true</td>
        </tr>
        <tr>
          <td>nzZIndex</td>
          <td>Modal zIndex属性，用于决定显示先后次序</td>
          <td>Number</td>
          <td></td>
          <td>1000</td>
        </tr>
        <tr>
          <td>nzStyle</td>
          <td>可用于设置浮层的样式，调整浮层位置等</td>
          <td>Object</td>
          <td></td>
          <td>-</td>
        </tr>
        <tr>
          <td>nzWrapClassName</td>
          <td>对话框外层容器的类名</td>
          <td>String</td>
          <td></td>
          <td>-</td>
        </tr>
        <tr>
          <td>open</td>
          <td>显示对话框方法</td>
          <td>Function</td>
          <td>可以通过 <code> #modal.open() </code>显示对话框，等同于<code> nzVisible = true </code></td>
          <td>-</td>
        </tr>
        <tr>
          <td>close</td>
          <td>关闭对话框方法</td>
          <td>Function</td>
          <td>可以通过 <code> #modal.close() </code>关闭对话框，等同于<code> nzVisible = false </code></td>
          <td>-</td>
        </tr>
        <tr>
          <td>setConfirmLoading</td>
          <td>设置确定按钮 loading 状态方法</td>
          <td>Function</td>
          <td>可以通过 <code> #modal.setConfirmLoading(true) </code> 设置确定按钮 loading 状态显示，参数为 false 则隐藏loading，等同于<code> nzConfirmLoading</code> </td>
          <td>-</td>
        </tr>
      </tbody>
    </table>
    <h2 id="NzModalService_xxx"><span>NzModalService.xxx()</span>
      <!-- <a class="anchor">#</a> -->
    </h2>
    <p>包括：</p>
    <ul>
      <li><p>NzModalService.open</p></li>
      <li><p>NzModalService.info</p></li>
      <li><p>NzModalService.success</p></li>
      <li><p>NzModalService.error</p></li>
      <li><p>NzModalService.warning</p></li>
      <li><p>NzModalService.confirm</p></li>
    </ul>
    <p>以上均为一个函数，参数为 object，具体属性如下：</p>
    <table>
      <thead>
        <tr>
          <th>参数</th>
          <th>说明</th>
          <th>类型</th>
          <th>支持程度</th>
          <th>默认值</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>title</td>
          <td>标题，如果不传，则不展示标题。</td>
          <td>String or TemplateRef</td>
          <td>All</td>
          <td>-</td>
        </tr>
        <tr>
          <td>content</td>
          <td>内容</td>
          <td>String or TemplateRef or Component</td>
          <td>All</td>
          <td>-</td>
        </tr>
        <tr>
          <td>zIndex</td>
          <td>Modal zIndex属性，用于决定显示先后次序</td>
          <td>Number</td>
          <td>All</td>
          <td>1000</td>
        </tr>
        <tr>
          <td>onOk</td>
          <td>点击确定回调，参数为关闭函数，<br/>返回 promise 时 resolve 后自动关闭</td>
          <td>function</td>
          <td>All</td>
          <td>无</td>
        </tr>
        <tr>
          <td>onCancel</td>
          <td>取消回调，参数为关闭函数，<br/>返回 promise 时 resolve 后自动关闭</td>
          <td>function</td>
          <td>All</td>
          <td>无</td>
        </tr>
        <tr>
          <td>width</td>
          <td>宽度</td>
          <td>String or Number</td>
          <td>All</td>
          <td>416</td>
        </tr>
        <tr>
          <td>okText</td>
          <td>确认按钮文字</td>
          <td>String</td>
          <td>All</td>
          <td>确定</td>
        </tr>
        <tr>
          <td>cancelText</td>
          <td>取消按钮文字</td>
          <td>String</td>
          <td>All</td>
          <td>取消</td>
        </tr>
        <tr>
          <td>iconType</td>
          <td>图标 Icon 类型</td>
          <td>String</td>
          <td>info/success/error<br/>/warning/confirm</td>
          <td>question-circle</td>
        </tr>
        <tr>
          <td>closable</td>
          <td>是否显示右上角的关闭按钮</td>
          <td>Boolean</td>
          <td>open</td>
          <td>true</td>
        </tr>
        <tr>
          <td>maskClosable</td>
          <td>点击蒙层是否允许关闭</td>
          <td>Boolean</td>
          <td>open</td>
          <td>true</td>
        </tr>
        <tr>
          <td>wrapClassName</td>
          <td>对话框外层容器的类名</td>
          <td>String</td>
          <td>open</td>
          <td>无</td>
        </tr>
        <tr>
          <td>footer</td>
          <td>底部内容，如果传入的是false，则不展示footer，方便用户在content里自定义自己想要的footer</td>
          <td>TemplateRef</td>
          <td>open</td>
          <td>无</td>
        </tr>
        <tr>
          <td>componentParams</td>
          <td>如果content传入的是Component的时候，通过componentParams来传入Component的参数</td>
          <td>Object</td>
          <td>open</td>
          <td>无</td>
        </tr>
        <tr>
          <td>showConfirmLoading</td>
          <td>如果footer没有指定（即展示默认footer）时，确定按钮在执行确定回调时是否显示 loading 状态</td>
          <td>Boolean</td>
          <td>All</td>
          <td>false</td>
        </tr>
      </tbody>
    </table>
    <h2 id="NzModalSubject"><span>NzModalSubject对象</span>
      <!-- <a class="anchor">#</a> -->
    </h2>
    <p>在弹出component中实例化NzModalSubject对象后可以通过next方法向外传输数据</p>
    <p>所有的NzModalService.xxx()方法都会返回一个NzModalSubject对象。</p>
    <p>这个对象是对rxjs的Subject对象的封装。除了支持Subject对象原生的方法外，还支持：</p>
    <ul>
      <li><code>NzModalSubject.destroy ( type )</code> - 用于销毁当前的modal对象</li>
      <li><code>NzModalSubject.on ( eventType, cb )</code> - 用于监听modal对象各个阶段的事件</li>
    </ul>
    <p>destroy方法中的type支持传入 <code>onOk</code> 和 <code>onCancel</code> ，表示销毁modal的时候会执行用户传入的options中的onCancel还是onOk方法</p>
    <p>NzModalSubject支持的所有eventType包括：</p>
    <ul>
      <li><p>onShow</p></li>
      <li><p>onShown</p></li>
      <li><p>onHide</p></li>
      <li><p>onHidden</p></li>
      <li><p>onOk</p></li>
      <li><p>onCancel</p></li>
      <li><p>onDestroy</p></li>
      <li><p>其他（ 用户可以自定义任何事件，都可以通过该对象监听 ）</p></li>
    </ul>
  </section>
</article>
